/*
 * Copyright (c) 2023 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @file queue.h
 *
 * @brief 声明串行队列提供的C接口.
 *
 * @since 10
 * @version 1.0
 */
#ifndef FFRT_API_C_QUEUE_H
#define FFRT_API_C_QUEUE_H

#include "type_def.h"

typedef enum { ffrt_queue_serial, ffrt_queue_max } ffrt_queue_type_t;
typedef void* ffrt_queue_t;

/**
 * @brief 初始化串行队列属性.
 *
 * @param attr 串行队列属性指针.
 * @return 执行成功时返回0,
           执行成功时返回-1.
 * @since 10
 * @version 1.0
 */
FFRT_C_API int ffrt_queue_attr_init(ffrt_queue_attr_t* attr);

/**
 * @brief 销毁串行队列属性.
 *
 * @param attr 串行队列属性指针.
 * @since 10
 * @version 1.0
 */
FFRT_C_API void ffrt_queue_attr_destroy(ffrt_queue_attr_t* attr);

/**
 * @brief 设置串行队列qos属性.
 *
 * @param attr 串行队列属性指针.
 * @param attr qos属性值.
 * @since 10
 * @version 1.0
 */
FFRT_C_API void ffrt_queue_attr_set_qos(ffrt_queue_attr_t* attr, ffrt_qos_t qos);

/**
 * @brief 获取串行队列qos属性.
 *
 * @param attr 串行队列属性指针.
 * @return 返回串行队列的qos属性
 * @since 10
 * @version 1.0
 */
FFRT_C_API ffrt_qos_t ffrt_queue_attr_get_qos(const ffrt_queue_attr_t* attr);

/**
 * @brief 创建队列.
 *
 * @param type 队列类型.
 * @param name 队列名字.
 * @param attr 队列属性.
 * @return 创建队列成功返回非空队列句柄
           创建队列失败返回空指针
 * @since 10
 * @version 1.0
 */
FFRT_C_API ffrt_queue_t ffrt_queue_create(ffrt_queue_type_t type, const char* name, const ffrt_queue_attr_t* attr);

/**
 * @brief 销毁队列.
 *
 * @param queue 队列句柄.
 * @since 10
 * @version 1.0
 */
FFRT_C_API void ffrt_queue_destroy(ffrt_queue_t queue);

/**
 * @brief 提交一个任务到队列中调度执行.
 *
 * @param queue 队列句柄.
 * @param f 任务的执行体.
 * @param attr 任务属性.
 * @since 10
 * @version 1.0
 */
FFRT_C_API void ffrt_queue_submit(ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr);

/**
 * @brief 提交一个任务到队列中调度执行，并返回任务句柄.
 *
 * @param queue 队列句柄.
 * @param f 任务的执行体.
 * @param attr 任务属性.
 * @return 提交成功返回非空任务句柄
           提交失败返回空指针
 * @since 10
 * @version 1.0
 */
FFRT_C_API ffrt_task_handle_t ffrt_queue_submit_h(
    ffrt_queue_t queue, ffrt_function_header_t* f, const ffrt_task_attr_t* attr);

/**
 * @brief 等待队列中一个任务执行完成.
 *
 * @param handle 任务句柄.
 * @since 10
 * @version 1.0
 */
FFRT_C_API void ffrt_queue_wait(ffrt_task_handle_t handle);

/**
 * @brief 取消队列中一个任务.
 *
 * @param handle 任务句柄.
 * @return 取消任务成功返回0
           取消任务失败返回-1
 * @since 10
 * @version 1.0
 */
FFRT_C_API int ffrt_queue_cancel(ffrt_task_handle_t handle);

#endif // FFRT_API_C_QUEUE_H